Skip to content

Document noise learning with CUDA-Q QEC for pre-decoder training - #103

Open
ivanbasov wants to merge 2 commits into
mainfrom
noise-learning-docs
Open

ivanbasov wants to merge 2 commits into
mainfrom
noise-learning-docs

Conversation

@ivanbasov

@ivanbasov ivanbasov commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

What

Documentation only.

  • New NOISE_LEARNING.md: how to estimate the 25-parameter circuit-level noise model from detector data with CUDA-Q QEC noise learning (cudaq_qec.plugins.nv_qldpc.learn_noise, mode="parametric", released in cudaq-qec 0.9.0) and write the result as a data.noise_model block for pre-decoder training.
  • One line in the "Noise model" section of README.md that links to it.

Why

data.noise_model is the input of training-data generation. When the device rates are unknown, they can be learned from recorded detector data without logical labels. The feature lives in CUDA-Q QEC; this page shows how to use it with the circuits and the config of this repository, and links to the CUDA-Q QEC documentation for the method itself.

For reviewers

  • Parameter naming. The surface-code circuits of this repository name a preparation/measurement parameter by the basis that fails (X_ERROR(p_prep_Z) after a Z-basis reset). The p25 helpers in cudaq-qec 0.9.0 name it by the applied Pauli and accept X_ERROR only for p_prep_X / p_meas_X. Without a conversion, p25.design_map rejects a tag circuit built by MemoryCircuit:
    ValueError: X_ERROR component X tagged as p_prep_Z: inconsistent with the circuit builder's conventions.
    The example exchanges the four keys when it builds the tag circuit and again on export, and the Notes section explains this. If the convention is aligned later on either side, the swap step can be removed. The color-code circuits read the four keys the other way; the guide says so and does not cover them.
  • Identifiability. One memory basis gives rank 23 of 25: in a Z-basis experiment p_prep_Z and p_meas_Z are fixed only together with p_cnot_XI and p_cnot_XX, and p_prep_X and p_meas_X only as a sum; the X basis mirrors this with p_cnot_IZ and p_cnot_ZZ. The two bases together give rank 25.
  • One noise model for both bases. Public training always generates data in both bases from one data.noise_model (config_validator.py sets meas_basis = "both" and rejects an override), so one block per basis cannot be used. The example fits the one set of 25 parameters that reproduces the mechanism rates learned in both bases (bounded least squares on the relative error, about ten lines with SciPy, which the inference requirements already include).

Changes after review

The first version combined the two single-basis results parameter by parameter (preparation and measurement from the run in their own basis, CNOT from the run that identifies them). That mixes values that are consistent only as a set, and the reported accuracy held only because the example's true p_cnot_XI and p_cnot_XX are nearly equal. With p_cnot_XI = 1.5e-3 and p_cnot_XX = 1e-4 that merge gave p_prep_Z at 0.80x and p_meas_Z at 1.42x of the truth, and mechanism rates off by up to about 20% in the Z basis. It is replaced by the joint fit above. Also changed: a sentence that the device must run the MemoryCircuit schedule, the parameter-name note scoped to the surface-code circuits, what a single-basis result can be used for, and the description of the learn_physical_params command-line tool.

Verification

The Python block was extracted verbatim from NOISE_LEARNING.md and run from the repository root on this branch:

  • cudaq-qec-cu12 0.9.0 from PyPI, stim 1.16.0, Python 3.11, one RTX PRO 6000.
  • Distance 7, 7 rounds, 262,144 simulated shots per basis, 16 passes: 56 s wall time in total.
  • Learned vs. true parameters: preparation and measurement within 2%, idle within 3%; 14 of 15 CNOT parameters within 20% (range 0.74x to 1.17x).
  • Mechanism rates of the learned model vs. the true model: median difference 0.4%, largest 1.2%, in each basis.
  • Same block with the true p_cnot_XI = p_cnot_ZZ = 1.5e-3 and p_cnot_XX = p_cnot_IZ = 1e-4: preparation and measurement within 3%, the two large CNOT parameters within 3%, the two small ones at 1.22x and 1.32x; 13 of 15 CNOT parameters within 20%; mechanism rates within 2.2% in each basis.
  • The written YAML loads through noise_model_from_config on top of conf/config_public.yaml.
  • learn_physical_params was run on these circuits: a tag circuit from unswapped tags is rejected with the error above; with swapped tags the --yaml output has the four prep/meas keys exchanged.

Not covered: a training run on the learned noise model, and detector data from a device (the example simulates the data).

No code, test or dependency changes.

🤖 Generated with Claude Code

Add NOISE_LEARNING.md: how to estimate the 25-parameter noise model from
detector data with cudaq-qec 0.9.0 (nv_qldpc.learn_noise, parametric mode)
and write it as a data.noise_model block for training. Link it from the
"Noise model" section of the README.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: Ivan Basov <ibasov@nvidia.com>
@ivanbasov
ivanbasov requested a review from bmhowe23 November 18, 2026 19:28

@bmhowe23 bmhowe23 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this is a useful page. I ran the Python block verbatim against cudaq-qec-cu12==0.9.0 and it reproduces the numbers in the description (rank 23 of 25 per basis; prep/meas/idle within 3%; 14 of 15 CNOT parameters within 20%).

One issue with how the two bases are merged (first inline comment), plus a few smaller doc points. The comment on the "Parameter names" note points at a naming inconsistency in this repo that predates the PR.

Limits of my own checks:

  • The unidentified directions mentioned in the comments on the merge loop and the "Use both bases" note were checked at d=3 and d=5 for the XV orientation only.
  • I did not check whether training mixes bases under one data.noise_model. If it does, the "one block per basis" advice needs rethinking.
  • For the surface-code / color-code naming comment I read the two circuit builders only. I did not check which convention precompute_dem or the training-data generator follow, and I did not run the color-code path.

Comment thread NOISE_LEARNING.md Outdated
Comment on lines +106 to +114
# Preparation and measurement parameters come from the experiment in their own basis,
# every other parameter from the runs that identify it on its own.
noise_model = {}
for k in p25.P25_PARAM_NAMES:
if k in SWAP:
runs = [k[-1]]
else:
runs = [b for b in learned if identifiable[b][k]] or list(learned)
noise_model[k] = float(np.mean([learned[b][k] for b in runs]))

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For training on one basis, I'd skip this merge and write each run's 25 values as its own block (e.g. learned_noise_model_Z.yaml, learned_noise_model_X.yaml). A single-basis run reproduces that basis's detector statistics exactly, even though some values are not individually determined. The merge here mixes values across runs: p_prep_Z/p_meas_Z from the Z run are only fixed together with p_cnot_XI/p_cnot_XX, which this loop takes from the X run (mirror for X with p_cnot_IZ/p_cnot_ZZ). With those CNOT rates unequal (d=5, 524k shots per basis, true p_cnot_XI=1.5e-3, p_cnot_XX=1e-4) I get p_prep_Z at 0.53x of truth in the merged model, and the merged set no longer matches either basis.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, the merge was wrong. Reproduced with p_cnot_XI = 1.5e-3, p_cnot_XX = 1e-4, d=5, 524k shots: p_prep_Z at 0.80x, p_meas_Z at 1.42x, and Z-basis mechanism rates off by up to about 20%. The numbers in the first version held only because the example's true p_cnot_XI and p_cnot_XX are nearly equal.

On one block per basis: public training always generates both bases from one data.noise_model (code/workflows/config_validator.py sets meas_basis = "both" and rejects a user override), so per-basis files cannot be used there. I kept one block and replaced the merge with a joint fit: the one set of 25 parameters that reproduces the mechanism rates learned in both runs (bounded least squares on the relative error). The stacked design of the two bases has rank 25.

Result of the block as written (d=7, 262,144 shots per basis), with true p_cnot_XI = p_cnot_ZZ = 1.5e-3 and p_cnot_XX = p_cnot_IZ = 1e-4: prep/meas within 3%, the two large CNOT values within 3%, the two small ones at 1.22x and 1.32x, mechanism rates within 2.2% of the true model in each basis.

Changed in 21baead.

Comment thread NOISE_LEARNING.md Outdated
Comment on lines +146 to +153
- **Use both bases.** One memory basis fixes 23 of the 25 parameter combinations.
`report["q_identifiable"]` marks the parameters that one experiment does not determine on
their own: the four preparation and measurement parameters and two CNOT parameters, a
different pair in each basis. A Z-basis experiment sees `p_prep_X` and `p_meas_X` only as
a sum and returns the same value for both; an X-basis experiment does the same for
`p_prep_Z` and `p_meas_Z`. The example therefore takes each preparation and measurement
parameter from the experiment in its own basis, and every other parameter from the runs
that identify it.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest reframing: a model learned from one basis is valid for generating data in that basis. Its prep/meas values and two CNOT values (p_cnot_XI/p_cnot_XX for Z, p_cnot_IZ/p_cnot_ZZ for X) are not the device's individual rates and should not be used for the other basis or quoted as device characterization.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rewritten along these lines in 21baead: the values learned from one basis reproduce the detector statistics of that basis, the six non-identifiable ones are not the device's individual rates, and they should not be used for the other basis or quoted as a characterization. I also added a separate note, "One noise model for both bases", on why training needs one set and why the two results must not be combined parameter by parameter.

Comment thread NOISE_LEARNING.md
Comment on lines +42 to +44
that the result can be compared with the truth. For a device, replace `dets` with the recorded
data: a `uint8` array of shape `[shots, detectors]`, with detectors in the order of the
circuit built by `MemoryCircuit` for the same distance, rounds, basis and orientation.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Detector order is necessary but not sufficient. The design is built from the fault locations of the MemoryCircuit circuit, so the device must have run that same schedule (CNOT order, idle placement, Z-basis measure/reset on ancillas). With a different schedule the data still has the right shape and learn_noise still runs, but rates are attributed to the wrong parameters. Worth one sentence here.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added in 21baead, after the sentence on detector order. One difference from the wording here: the surface builder does not use Z-basis reset/measure on all ancillas. It emits RX/MRX for X-stabilizer ancillas and R/MR for Z-stabilizer ancillas, with no Hadamards, so the sentence lists the CNOT order, the idle locations, and ancilla preparation and measurement in the X basis for X stabilizers and in the Z basis for Z stabilizers.

Comment thread NOISE_LEARNING.md Outdated
Comment on lines +139 to +142
- **Parameter names.** In this repository `p_prep_Z` and `p_meas_Z` are the failure
probabilities of a Z-basis preparation and measurement (an X flip). `cudaq_qec`'s `p25`
helpers name the same parameters by the applied Pauli (`p_prep_X`, `p_meas_X`). The `swap`
step in the example converts between the two; without it `p25.design_map` rejects the

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"In this repository p_prep_Z and p_meas_Z are the failure probabilities of a Z-basis preparation and measurement" holds for the surface-code builder only. The color-code builder reads the same four keys the other way:

  • code/qec/surface_code/memory_circuit.py (add_reset, add_measure): Z-basis reset/measure gets X_ERROR(p_prep_Z) / X_ERROR(p_meas_Z). This matches the comments in conf/config_public.yaml.
  • code/qec/color_code/memory_circuit.py:558-566 and :844-852: Z-basis reset/measure gets X_ERROR(p_prep_X) / X_ERROR(p_meas_X).

The shipped configs set all four values equal, so this is invisible today, but a learned (non-uniform) model makes it matter. Not something to fix in this PR; suggest scoping the sentence to "the surface-code circuits of this repository" and opening a separate issue for the color-code builder. It also means the cudaq-qec p25 naming agrees with the color-code builder, so the swap step is specific to surface code.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed in both builders. In 21baead the sentence is scoped to the surface-code circuits of this repository, the note says the swap step is specific to them, and the "Surface code only" note now states that the color-code circuits read the four prep/meas keys the other way. The color-code builder itself is not touched here; it is a separate issue.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up: instead of an issue, I am fixing the color-code builder in a separate PR. It moves the color-code path to the surface-code convention (a key is named by the basis that fails), which is what conf/config_public.yaml and the README describe; the surface builder and the config stay as they are. I will link it here once it is open. When it merges, the sentence in this guide about the color-code circuits reading the keys the other way will be updated.

Comment thread NOISE_LEARNING.md Outdated
Comment on lines +143 to +145
circuit. Because of this, the `--tag-circuit` and `--yaml` options of the
`cudaq_qec.plugins.nv_qldpc.cli.learn_physical_params` command-line tool write the four
prep/meas keys exchanged for this repository.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: --tag-circuit does not write anything. Suggest: "The learn_physical_params command-line tool rejects a tag circuit built by MemoryCircuit from unswapped tags, and with swapped tags its --yaml output has the four prep/meas keys exchanged for this repository."

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied this wording in 21baead. I also ran the tool on these circuits: a tag circuit built from unswapped tags is rejected with the same ValueError as p25.design_map, and with swapped tags the --yaml output has the four prep/meas keys exchanged.

Address review comments on the noise learning guide.

The example combined the two single-basis results parameter by
parameter. One memory basis fixes the preparation and measurement
parameters only together with two CNOT parameters, so values taken from
different runs do not form a consistent set. The example now fits the
one set of 25 parameters that reproduces the mechanism rates learned in
both bases; the two experiments together fix all 25.

Also state that the device must run the MemoryCircuit schedule, scope
the parameter-name note and the swap step to the surface-code circuits,
say what a single-basis result can be used for, and correct the
description of the learn_physical_params command-line tool.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: Ivan Basov <ibasov@nvidia.com>
@ivanbasov

Copy link
Copy Markdown
Member Author

@bmhowe23 thanks for the review. All five comments are addressed in 21baead, with a reply in each thread; the PR description has the updated verification numbers. Could you take another look?

The main change is the example: the per-parameter merge of the two bases is replaced by one fit of the 25 parameters to the results of both bases. The answer to the open question in the review is that public training always uses both bases under one data.noise_model, which is why the guide keeps a single block instead of one per basis.

The change is documentation only. Unit tests and the style checks pass on 21baead; the GPU jobs are still running.

@ivanbasov
ivanbasov requested a review from bmhowe23 November 19, 2026 01:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants